Itential Automation Platform

API breaking changes for Pre-built Automations (2021.1.4)

The following Admin Essentials APIs have introduced breaking changes for the 2021.1.4 release:

• POST /prebuilts/import
• DELETE /prebuilts/:id

Note: Refer to the Itential Breaking Changes for more documentation on the breaking changes introduced.

JST 'extractOutput' has been restored within the JST Task (2021.1.2)

Itential removed the extractOutput checkbox from the JST task in 2020.2.5 which also removed this option in the 2021.1 release of IAP. After some consideration, we decided to readd this configuration option back in 2021.1.2. Users now are able to change this value in Automation Studio.

Please note that up to this point in 2021.1, this option has defaulted to 'false.' Going forward, for new development, it will default to 'true' which will change the output when used with a single schema output JST as per the documentation. On the other hand, any existing development that had previously set this value to 'false' will be unchanged, but the user interface will allow the workflow designer to modify its value. Finally, any JST with an extractOutput=true that returns as undef, will cause the task to error and must be handled appropriately.

Health Module APIs

The following APIs have been deprecated and will be removed in the 2021.2 release.

Note: Refer to the Itential API Guide for documentation on the replacement /health APIs listed below.

Item	Description	Replacement
GET /health/modules	Get the health data of all current services in IAP.	GET /health/adapters or GET /health/applications
GET /health/module/:module	Get the health data for a single service in IAP.	GET /health/adapters/:name or GET /health/applications/:name

Modification to getJobDetails API (2021.1.2)

The GET /workflow_engine/job/:job_id/details API, or WorkFlowEngine.getJobDetails, has been modified as part of the 2021.1.2 maintenance release. Now, in addition to all the fields that existed before, the transitions field is also returned, which contains data from the workflow about how tasks connect to other tasks.

Using GET /isAlive with Monitoring Systems (2021.1.0)

The API GET /isAlive has been removed from the system and should be replaced with GET /status. Both APIs respond with the HTTP status code but the only difference between the two API requests is GET /status responds with the actual status and GET /isAlive responded with a happy or sad face. Please update any external monitoring systems (e.g., load balancers) that might have used the API looking for the happy or sad face.

Mongo Indexes Renamed

As part of the 2021.1 release, Itential has added proper names for our indexes in Mongo. These indexes will start with the prefix itential_ and then contain information about the contents or purpose of the index. With a prefix placed at the beginning, Mongo adminstrators will more easily be able to distinguish Itential out-of-the box indexes as opposed to other custom indexes that could potentially be interferring or duplicating efforts.

Since indexes previously did not have a name, the names were autogenerated by Mongo. For example, an index in Workflow Engine had the following key:

{
    "name" : 1,
    "type" : 1,
    "groups" : 1,
    "status" : 1,
    "metrics.start_time" : -1,
    "metrics.progress" : 1,
    "metrics.user" : 1
}

The key was then used to automatically create the following name:

name_1_type_1_groups_1_status_1_metrics.start_time_-1_metrics.progress_1_metrics.user_1

Long names like this can eventually cause problems in Mongo (especially when moving environments) even to the point of failure as some Mongo versions limit indexes to 127 characters in length. Additionally they are not easily readable by users. With the new prefix, the index will instead have the following name:

itential_groups_metrics

What should I do?

It is not possible to rename an index in Mongo after it has been created. Renaming an index requires dropping and recreating that index with the new name.

The process is automatically handled by new indexing APIs within IAP, although on large collections this process may take some time to complete. That being the case, Itential recommends indexes are created during a maintenance window for larger collections.

Index creation can either be initiated from the Admin Essentials UI or via the following APIs:

• GET /indexes will retrieve all collections that may need to be indexed.

• POST /indexes/${collectionName} will initiate the creation of all predefined indexes for a collection.

Once the process commences, it will create all indexes that are missing as well as drop and rename any pre-defined indexes that had an auto-generated name.

Renamed indexes

The following indexes have been renamed to reflect the addition of the itential_ prefix, and will be dropped and recreated with said name when the indexes are created through IAP.

Collection	Previous Name	New Name
accounts	provenance_1_username_1	itential_provenance_username
catalog_store	name_1	itential_name
catalog_store	workflow_1	itential_workflow
forms	name_1	itential_name
groups	provenance_1_name_1	itential_provenance_name
groups	inactive_1	itential_inactive
iap_profiles	id_1	itential_id
integration_models	versionId_1	itential_versionId
jobs	name1_type_1_groups_1_status_1_metrics.start_time-1_metrics.progress_1_metrics.user_1	itential_groups_metrics
jobs	name1_type_1_watchers_1_status_1_metrics.start_time-1_metrics.progress_1_metrics.user_1	itential_watchers_metrics
jobs	parent.job_1	itential_parent
jobs	metrics.start_time_1	itential_mst
jobs	metrics.user_1	itential_metrics.user
jobs	groups_1	itential_groups
jobs	name_1	itential_name
jobs	status_1	itential_status
jobs	metrics_1	itential_metrics
jobs	status_1_groups_1	itential_status_groups
jobs	watchers_1	itential_watchers
mop_templates	name_1	itential_name
mop_analytic_templates	name_1	itential_name
roles	provenance_1_name_1	itential_provenance_name
service_configs	name_1	itential_name
tags	name_1	itential_name
tasks	name1_status_1_groups_1_type_1_job.name_1_job._id_1_job.task_1_metrics.owner_1_metrics.start_time-1	itential_task_metadata
tasks	job._id_1_job.task_1	itential_job
tasks	groups_1	itential_groups
tasks	job._id_1	itential_job.id
tasks	metrics.owner_1	itential_metrics.owner
tasks	metrics.start_time_1	itential_mst
transformations	name_1	itential_name
transformations	incoming.°\$id_1	itential_incoming
transformations	outgoing.°\$id_1	itential_outgoing
ucm_configs	name_1	itential_name
workflows	name_1_type_1	itential_name_type
worfklows	name_1	itential_name
workflows	groups1_created-1created_by_1_last_updated-1_last_updated_by_1	itential_update_metadata

Adapter Deletion within Admin Essentials (2021.1.0)

Previously, Admin Essentals would not allow a user to delete an adapter that was in a profile. Now adapters can be deleted from Admin Essentials regardless of their status in the system profiles. On delete, a warning message will appear and then the adapter will be stopped and removed from every profile where it is found.

Problem Explanation

In an HA environment with three servers (i.e., IAP1, IAP2, IAP3), when an adapter instance is deleted from IAP1, two things happen:

1. The adapter is "stopped" which kills the node process in IAP1.
2. The adapter is removed from the profiles it is in.

Keep in mind that technically, IAP2 and IAP3 will still have their instance of the adapter running in memory. With the first action above, once the instance was deleted, the adapter was automatically "stopped" in IAP 1 only. This was not automatically applied for the other servers. Consequently, the user should also "stop" the adapter on IAP2 and IAP3. Otherwise, this could cause the instances in an HA environment to be out-of-sync.

New Job Details Permission

Viewing the Job Details pages now requires a new permission getJobDetails (defined within WorkflowEngine) that may not be enabled in some customers' custom roles. If you have custom roles and want those roles to access the Job Details page, then ensure they have access to either the WorkFlowEngine apiread role or the getJobDetails method. Hint: To do this, find the custom role in Authorization Manager, search for getJobDetails in the WorkFlowEngine application, and add it to the role.